﻿namespace Sage.CloudStorage.Qiniu.Models
{
    /// <summary>
    /// 七牛云密钥信息类
    /// 包含访问七牛云服务所需的AccessKey和SecretKey
    /// </summary>
    /// <remarks>
    /// **密钥说明**：
    /// - **AccessKey**：公开密钥，用于标识用户身份，可以在客户端使用
    /// - **SecretKey**：私密密钥，用于签名验证，绝对不能暴露给客户端
    /// 
    /// **安全要求**：
    /// - SecretKey必须保密，只能在服务端使用
    /// - 定期轮换密钥以提高安全性
    /// - 使用环境变量或配置文件存储，避免硬编码
    /// - 不要将SecretKey提交到版本控制系统
    /// 
    /// **获取方式**：
    /// 1. 登录七牛云控制台
    /// 2. 进入"个人中心" -> "密钥管理"
    /// 3. 创建或查看AccessKey/SecretKey对
    /// </remarks>
    /// <param name="accessKey">七牛云AccessKey，用于身份标识</param>
    /// <param name="secretKey">七牛云SecretKey，用于签名验证</param>
    /// <exception cref="ArgumentNullException">当accessKey或secretKey为null时抛出</exception>
    public class QiniuKey(string accessKey, string secretKey)
    {
        /// <summary>
        /// 七牛云AccessKey（公开密钥）
        /// 用于标识用户身份，可以在API请求中公开传输
        /// </summary>
        /// <remarks>
        /// AccessKey特点：
        /// - 长度通常为40个字符
        /// - 可以安全地在客户端和网络传输中使用
        /// - 用于生成签名中的身份标识部分
        /// - 可以在日志中记录（不涉及安全风险）
        /// </remarks>
        public string AccessKey { get; } = accessKey ?? throw new ArgumentNullException(nameof(accessKey));

        /// <summary>
        /// 七牛云SecretKey（私密密钥）
        /// 用于HMAC签名计算，必须严格保密
        /// </summary>
        /// <remarks>
        /// SecretKey特点：
        /// - 长度通常为40个字符
        /// - 绝对不能暴露给客户端或第三方
        /// - 用于HMAC-SHA1签名计算
        /// - 泄露后需要立即重新生成
        /// 
        /// 安全警告：
        /// - 不要在客户端代码中硬编码SecretKey
        /// - 不要将SecretKey提交到公开的代码仓库
        /// - 不要在日志中记录SecretKey
        /// - 不要通过HTTP GET参数传递SecretKey
        /// </remarks>
        public string SecretKey { get; } = secretKey ?? throw new ArgumentNullException(nameof(secretKey));

        /// <summary>
        /// 验证密钥是否有效
        /// 检查AccessKey和SecretKey是否符合基本格式要求
        /// </summary>
        /// <returns>如果密钥格式有效返回true，否则返回false</returns>
        /// <remarks>
        /// 验证规则：
        /// - AccessKey和SecretKey不能为null或空白
        /// - 长度至少为10个字符（七牛云密钥通常为40字符）
        /// - 此方法只做基本格式验证，不验证密钥的有效性
        /// 
        /// 注意：此验证不能保证密钥在七牛云服务中是有效的，
        /// 只能确保格式符合基本要求。真正的有效性需要通过API调用验证。
        /// 
        /// 使用场景：
        /// - 初始化前的参数检查
        /// - 配置文件加载后的验证
        /// - 用户输入密钥的基本校验
        /// </remarks>
        public bool IsValid()
        {
            return !string.IsNullOrWhiteSpace(AccessKey) &&
                   !string.IsNullOrWhiteSpace(SecretKey) &&
                   AccessKey.Length >= 10 &&
                   SecretKey.Length >= 10;
        }

        /// <summary>
        /// 重写ToString方法，提供安全的字符串表示
        /// 为了安全考虑，不会显示完整的SecretKey
        /// </summary>
        /// <returns>包含AccessKey和部分SecretKey的安全字符串</returns>
        /// <remarks>
        /// 安全设计：
        /// - 完整显示AccessKey（因为它是公开的）
        /// - 只显示SecretKey的前4位和后4位
        /// - 中间用"****"替代，保护完整SecretKey不被泄露
        /// 
        /// 输出格式示例：
        /// "QiniuKey { AccessKey: abc123..., SecretKey: xyz1****890z }"
        /// 
        /// 用途：
        /// - 调试输出和日志记录
        /// - 开发过程中的状态检查
        /// - 不会泄露敏感信息的情况下提供有用信息
        /// </remarks>
        public override string ToString()
        {
            var maskedSecretKey = SecretKey.Length > 8
                ? SecretKey[..4] + "****" + SecretKey[^4..]
                : "****";

            return $"QiniuKey {{ AccessKey: {AccessKey}, SecretKey: {maskedSecretKey} }}";
        }
    }
}
